Project files

STM32CubeIDE for Visual Studio Code uses project files from STM32 tools, CMake, and Visual Studio Code. Understanding the role of each file helps developers know where to configure the project and which files are generated.

The same workspace can contain files with different owners. Some files come from STM32CubeMX, some files describe the build system, and some files are local editor configuration. Knowing the owner of a file helps prevent edits that are lost during regeneration.

Important file groups

An STM32 workspace commonly contains these file groups:

  • STM32CubeMX configuration files, such as .ioc files

  • Application source files, headers, startup files, and linker scripts

  • CMake files and CMake preset files

  • Visual Studio Code files in the .vscode folder

  • Build output folders, such as build or configuration-specific output folders

The exact layout depends on how the project was created, imported, or generated.

Most project folders also contain documentation, scripts, or application-specific assets. These files are part of the product workflow but are not necessarily interpreted by STM32CubeIDE for Visual Studio Code.

STM32CubeMX configuration

The STM32CubeMX configuration stores the selected device or board, clock configuration, peripheral settings, middleware selections, and code generation options. STM32CubeIDE for Visual Studio Code can use this information when importing or discovering a project.

When STM32CubeMX regenerates code, review the changed files before committing. Regeneration can update startup files, initialization code, middleware configuration, and build files.

Use STM32CubeMX as the main source for hardware and middleware configuration. If a generated source file needs application code, place the code in the user sections provided by the generator when they are available.

CMake project files

CMake files define how the project builds. They describe source files, include paths, compile definitions, linker inputs, and build targets.

CMake preset files define named configure and build contexts. In Visual Studio Code, selecting a preset tells the CMake extension and STM32CubeIDE workflow which build configuration to use.

The preset name usually reflects the intended build mode, such as Debug or Release. A Debug preset typically keeps debug symbols and lower optimization, while a Release preset usually enables stronger optimization and produces a smaller or faster image.

For CMake concepts, see CMake.

Visual Studio Code configuration

The .vscode folder can contain project-specific configuration files:

  • settings.json for workspace settings

  • tasks.json for build, test, or utility tasks

  • launch.json for debug launch configurations

  • extensions.json for recommended extensions

Version-control these files when they define the shared team workflow. Keep user-specific values, local paths, and temporary experiments out of shared configuration files.

For example, a shared launch.json can define the standard debug probe and executable path for the team. A user-specific setting, such as a local tool path, is better kept in user settings or documented as a setup requirement.

Build output

Build output folders contain generated files such as object files, executable files, map files, and logs. These files depend on the selected preset and target.

Do not edit build output files manually. If an output is incorrect, change the project configuration or source files, then rebuild.

Build output is useful for diagnosis. The .elf file contains symbols for debugging, the .map file helps analyze memory usage, and build logs help identify compiler or linker errors.